home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1993…ch: Other People's Memory / ADC Developer CD (1993-03) (''Other People's Memory'')_iso / Dev.CD Mar 93.iso / Development Platforms / LISP Related / LISP Goodies / Cartiers-Contribs / Modules / extended-apropos / HELP < prev    next >
Encoding:
Text File  |  1992-09-08  |  7.7 KB  |  185 lines  |  [TEXT/CCL2]
  1. Extended Apropos: A Symbol Search Laboratory
  2.  
  3.   This set of files implements an extended Apropos dialog. It is a
  4.   superset of MCL's standard Apropos dialog. You can use it to search
  5.   for all of lisp symbols that match certain criteria.
  6.  
  7. Copyright
  8.  
  9.                  Extended Apropos: A Symbol Search Laboratory
  10.                  Copyright 1992 by Guillaume Cartier
  11.  
  12.   Permission to use, copy, modify, and distribute this software and its
  13.   documentation for any purpose and without fee is hereby granted, provided
  14.   that this copyright and permission notice appear in all copies and supporting
  15.   documentation. There is no representations about the suitability of this
  16.   software for any purpose. It is provided "as is" without express or implied
  17.   warranty.
  18.  
  19. Obtaining the Software
  20.  
  21.   This software can be obtained by anonymous ftp at cambridge.apple.com
  22.   under directory pub/mcl2/contrib. If you do not have ftp access, you
  23.   can contact:
  24.                 Guillaume Cartier
  25.                 Email: cartier@math.uqam.ca
  26.  
  27. Change Log
  28.  
  29.   17/03/92   First Release.
  30.   08/04/92   Corrected a bug reported by Michael Wirth which could
  31.              cause problems when you saved an application.
  32.   22/04/92   Made two cosmetic improvements suggested by Kemi Jona.
  33.   22/04/92   Added a global variable *DEFAULT-PACKAGE* (to be found
  34.              in the "apropos.lisp" file) that determines what package
  35.              will be selected by default when the extended apropos
  36.              is first brought up. This can be usefull, as I found I
  37.              was selecting the "CL-USER" package 99% of the time!
  38.              The extended apropos will now also remember what package
  39.              is selected when you close its window.
  40.   06/05/92   Moving through the found symbols using the arrow keys
  41.              did not update the state of the action buttons (reported
  42.              by Matthew Cornell).
  43.  
  44. To Do
  45.  
  46. Notes
  47.  
  48.   The original idea for an extended apropos dialog came from
  49.   Cristopher Fry's smart apropos dialog written in MCL 1.1.
  50.  
  51. For MCL2.0b1p3 Users
  52.  
  53.   Here are the steps needed to convert extended apropos to MCL 2.0b1p3:
  54.   (should take less than 5 minutes)
  55.  
  56.     - In the "LOADME" file, comment the 2 REQUIRE.
  57.       (you won't get the nice ballow help, but I suppose you can live with that) :-)
  58.  
  59.     - In the "LOADME" file, comment the following line:
  60.       "%BUFFER-SET-READ-ONLY"
  61.  
  62.     - In the "apropos.lisp" file, comment the following line:
  63.       (make-instance 'search-thermometer :view-position #@(482 181))
  64.  
  65.     - In the "subviews.lisp" file, comment the following line: (at the top)
  66.       (%buffer-set-read-only buffer t)
  67.  
  68.     - In the "subviews.lisp" file, replace the APROPOS-FILTER function
  69.       with the following one: (you may want to do a search on this one...)
  70.       (defun apropos-filter (symbols filter)
  71.         (prog1 (filter symbols filter)
  72.           (unless (and *foreground*
  73.                        (eq *apropos* (front-window)))
  74.             (ed-beep))))
  75.  
  76.   That's it.
  77.   Have fun.
  78.  
  79.   NB: I haven't tested all of extended apropos's features in MCL 2.0b1p3,
  80.       but the most important ones should work fine.
  81.  
  82.   NB: If you experiment any problems using this procedure,
  83.       let me know, I will see what can be done.
  84.  
  85. Documentation
  86.  
  87.   Using the extended apropos should be strait forward. Balloon help is
  88.   supported and can provide documentation for specific parts of the dialog.
  89.   Try out balloon help on the list of found symbols for a nice feature.
  90.  
  91.   The only hidden feature of the extended apropos is the fact that the
  92.   window can be resized even though it hasn't got a grow icon. That was
  93.   a small concession I had to make to save screen space and make the
  94.   dialog fit on small macintosh screens.
  95.  
  96.   There are three accelerators available in the found symbols table,
  97.   corresponding to the three buttons on the right side:
  98.  
  99.     - double-clicking, control-clicking or command-clicking will inspect
  100.       the selected symbol.
  101.     - option-clicking will show documentation for the selected symbol.
  102.     - option-control-clicking or option-command-clicking will edit the
  103.       definition of the selected symbol.
  104.  
  105.   The extended apropos defines a copy method that copies the selected
  106.   symbol's name to the clipboard (meaning you can use the Copy menu item
  107.   on the extended apropos to save some typing).
  108.  
  109. Tutorial
  110.  
  111.   This section provides step by step examples on how to use some of
  112.   the features provided by the extended apropos.
  113.  
  114.   Scenario 1:
  115.  
  116.     - I want to find every function that relates to events and windows.
  117.     - I type "event" in the text box and then click "Search".
  118.     - Hum... that's to much symbols, I really don't care about all the
  119.       internal ones, I would like to see only the external ones...
  120.     - I select "Show only external symbols" and then click "Refine".
  121.     - That's better.
  122.     - Then I want only the symbols that relate to windows, so I type
  123.       "window" and click "Refine".
  124.     - Now I want only the symbols that represent functions so I select
  125.       "name represents a function type: any" and click "Refine" (not
  126.       forgeting to check the check box).
  127.  
  128.   Note: When you only want to see the 'official' symbols, i.e. the external
  129.         ones, a trick that will do it nicely and very fastly is to select the
  130.         "common-lisp-user" package and "Show only inherited symbols". This will
  131.         give you all the external symbols of both the "common-lisp" and the
  132.         "ccl" packages.
  133.  
  134.   Scenario 2:
  135.  
  136.     - I want to really delve into views, including all the internal stuff.
  137.     - I type "view"
  138.     - I select "Search into all packages" and "Show all symbols".
  139.     - I click "Search" (it takes some time).
  140.     - As I know this will be my base for future exploration, I anchor the
  141.       found symbols as the base for future searches by clicking "Anchor".
  142.     - I would like to know all of the found symbols which are functions, so I
  143.       select "name represents a function type: any" and click "Search" (note
  144.       that this search will be done only on the previously anchored symbols).
  145.     - Hum... I wonder if any of those symbols are documented, so I select
  146.       "documentation is available" and click "Refine".
  147.     - Having done some exploration on functions, I now want to find which of
  148.       those symbols are proclaimed special.
  149.     - I select "name represents a value type: any" and click "Search".
  150.     - Now I would like to have an idea of what their symbol values are, so
  151.       I select "Show value" and check the check box in front of it.
  152.  
  153.   Scenario 3: (here is one for the developers) :-)
  154.  
  155.     - I wonder which symbols are still missing documentation and so will
  156.       have to be documented for the final release.
  157.     - Type in "" (search for ALL symbols).
  158.     - Select the "common-lisp-user" package and "Show only inherited symbols".
  159.     - Select "documentation is not available".
  160.     - If necessary, click "Global" to restore the search domain to all symbols.
  161.     - Click "Search".
  162.     - Here are all the symbols that still have to be documented...
  163.  
  164.   Scenario 4: (remember all those discussions on warnings!)
  165.  
  166.     - I wonder what are all the warnings that MCL knows of.
  167.     - Type in "".
  168.     - Select package "ccl" and "Show all symbols".
  169.     - Select "name represents a condition: warning".
  170.     - Click "Search".
  171.  
  172.   Note: Some searches such as the one above can be lengthy. This is no
  173.         problem! The searches can be done in background! Start the search
  174.         and then continue whatever you where doing. When the search is
  175.         finished, you will told so by a beep (the apropos will beep only if
  176.         its window is not frontmost or if MCL is not the current application).
  177.  
  178. References
  179.  
  180.   - Common Lisp the Language, Second Edition,
  181.     Guy L. Steele Jr., Digital Press 1990
  182.  
  183.   - Macintosh Common Lisp 2.0 Reference (Draft)
  184.     Apple Computer, Inc. 1991
  185.